Skip to main content
GET
/
api
/
v1
/
agents
List Agents
curl --request GET \
  --url https://api.example.com/api/v1/agents
{
  "items": [
    {
      "id": "<string>",
      "gateway_id": "<string>",
      "board_id": "<string>",
      "name": "<string>",
      "status": "<string>",
      "gateway_agent_id": "<string>",
      "workspace_path": "<string>",
      "is_mc_agent": true,
      "is_board_lead": true,
      "is_gateway_main": true,
      "openclaw_session_id": "<string>",
      "last_seen_at": {},
      "created_at": {},
      "updated_at": {},
      "heartbeat_config": {},
      "identity_profile": {}
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123
}
Returns a paginated list of agents for the authenticated user’s organization. Results can be filtered by board, gateway, or whether the agent is managed by Mission Control.

​
Authentication

Requires organization admin authentication via Authorization: Bearer <token> header.

​
Query Parameters

​
board_id
UUID
Filter agents by board ID
​
gateway_id
UUID
Filter agents by gateway ID
​
is_mc_agent
boolean
Filter for agents managed by Mission Control (true) or manually configured agents (false)
​
limit
integer
default:"50"
Number of items per page (max 100)
​
offset
integer
default:"0"
Number of items to skip for pagination

​
Response

​
items
AgentRead[]
Array of agent objects
​
id
UUID
Agent UUID
​
gateway_id
UUID
Gateway UUID that manages this agent
​
board_id
UUID
Board ID this agent is scoped to (null for gateway main agents)
​
name
string
Human-readable agent display name
​
status
string
Lifecycle state: provisioning, ready, active, idle, paused, deleted
​
gateway_agent_id
string
Stable gateway agent ID in the OpenClaw runtime (e.g., agent-01J...)
​
workspace_path
string
Workspace path on the gateway host (e.g., /home/ubuntu/.openclaw/workspace-main)
​
is_mc_agent
boolean
Whether this agent is managed by Mission Control
​
is_board_lead
boolean
default:"false"
Whether this agent is the board lead
​
is_gateway_main
boolean
default:"false"
Whether this agent is the primary gateway agent
​
openclaw_session_id
string
OpenClaw session token (e.g., sess_01J...)
​
last_seen_at
datetime
Last heartbeat timestamp
​
created_at
datetime
Creation timestamp
​
updated_at
datetime
Last update timestamp
​
heartbeat_config
object
Runtime heartbeat behavior overrides
{
  "interval_seconds": 30,
  "missing_tolerance": 120
}
​
identity_profile
object
Profile hints for routing and policy
{
  "role": "incident_lead",
  "skill": "triage"
}
​
total
integer
Total number of agents matching the filters
​
limit
integer
Items per page
​
offset
integer
Current offset

​
Example Request

curl -X GET "https://api.example.com/api/v1/agents?board_id=550e8400-e29b-41d4-a716-446655440000&limit=20" \
  -H "Authorization: Bearer your-token-here"

​
Example Response

{
  "items": [
    {
      "id": "c91361ef-6d85-439c-82e1-8f388a302e6a",
      "gateway_id": "55cc268a-4b45-400f-accf-201e025232ac",
      "board_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Clawd-CFO",
      "status": "active",
      "gateway_agent_id": "agent-01JCXYZ123",
      "workspace_path": "/home/ubuntu/.openclaw/workspace-mc-c91361ef",
      "is_mc_agent": true,
      "is_board_lead": true,
      "is_gateway_main": false,
      "openclaw_session_id": "agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main",
      "last_seen_at": "2026-03-05T10:30:00Z",
      "created_at": "2026-03-01T08:00:00Z",
      "updated_at": "2026-03-05T10:30:00Z",
      "heartbeat_config": {
        "interval_seconds": 60
      },
      "identity_profile": {
        "role": "board_lead",
        "specialty": "financial_ops"
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

​
Use Cases

  • Admin Dashboard: Display all agents across the organization
  • Board View: Filter agents by board_id to show board-specific agents
  • Gateway Management: Use gateway_id to see all agents on a specific gateway
  • Monitoring: Check last_seen_at to identify offline agents